@stratasync/y-doc 0.2.0

package/README.md

@@ -0,0 +1,44 @@
+# @stratasync/y-doc
+
+Yjs CRDT utilities and integration for collaborative editing in the Done.
+
+## Overview
+
+sync-yjs provides Yjs document management and protocol utilities:
+
+- **Document management** — create and manage Yjs documents for collaborative fields
+- **Awareness protocol** — presence and cursor tracking across clients
+- **Delta serialization** — encode/decode Yjs updates for transport
+- **Sync protocol** — state vector exchange and update application
+
+## Installation
+
+```bash
+npm install @stratasync/y-doc
+```
+
+Dependency: `yjs` ^13.6.21
+
+## Usage
+
+```typescript
+import { createYjsManager } from "@stratasync/y-doc";
+
+const yjsManager = createYjsManager();
+
+// Create a document for a collaborative field
+const doc = yjsManager.getOrCreateDoc("Task", taskId, "description");
+
+// Encode state for transport
+const update = Y.encodeStateAsUpdate(doc);
+
+// Apply remote update
+Y.applyUpdate(doc, remoteUpdate);
+```
+
+## Concepts
+
+- **One Yjs document per collaborative field** — e.g., `Task.description` gets its own doc
+- **Awareness** — separate protocol for presence (cursors, selections, user info)
+- **Binary encoding** — Yjs uses efficient binary encoding, not JSON
+- **Conflict-free** — CRDT guarantees eventual consistency without server coordination

package/dist/document-manager.d.ts

@@ -0,0 +1,91 @@
+/**
+ * YjsDocumentManager - Manages local Y.Doc instances for collaborative editing.
+ *
+ * Responsibilities:
+ * - Create and manage Y.Doc instances per document field
+ * - Handle Yjs sync protocol (state vector exchange)
+ * - Apply local and remote updates
+ * - Track connection state per document
+ * - Generate derived content from Y.Doc
+ */
+import * as Y from "yjs";
+import type { ConnectOptions, DocumentConnectionState, DocumentKey, YjsDocumentManagerConfig, YjsTransport } from "./types.js";
+/**
+ * Manages Y.Doc instances for collaborative editing.
+ */
+export declare class YjsDocumentManager {
+    private readonly docs;
+    private readonly remoteUpdateOrigin;
+    private readonly config;
+    private readonly liveEditingRetryConfig;
+    private persistenceKeyPrefix;
+    private transport;
+    private transportConnectionState;
+    private unsubscribeTransportMessage;
+    private unsubscribeTransportConnection;
+    private readonly connectionStateCallbacks;
+    private readonly contentCallbacks;
+    constructor(config: YjsDocumentManagerConfig);
+    setPersistenceKeyPrefix(prefix: string): void;
+    clearPersistedDocuments(): void;
+    setTransport(transport: YjsTransport): void;
+    getDocument(docKey: DocumentKey): Y.Doc;
+    /**
+     * Connect to a document for collaborative editing.
+     */
+    connect(docKey: DocumentKey, options?: ConnectOptions): void;
+    disconnect(docKey: DocumentKey): void;
+    getConnectionState(docKey: DocumentKey): DocumentConnectionState;
+    onConnectionStateChange(docKey: DocumentKey, callback: (state: DocumentConnectionState) => void): () => void;
+    onContentChange(docKey: DocumentKey, callback: (content: string) => void): () => void;
+    /**
+     * Apply a remote update to a document.
+     */
+    applyRemoteUpdate(docKey: DocumentKey, update: Uint8Array): void;
+    /**
+     * Apply a snapshot (full state) to a document.
+     * Semantically identical to applyRemoteUpdate — a Yjs snapshot
+     * is applied using the same Y.applyUpdate mechanism.
+     */
+    applySnapshot(docKey: DocumentKey, snapshot: Uint8Array): void;
+    getDerivedContent(docKey: DocumentKey): string;
+    getStateVector(docKey: DocumentKey): Uint8Array;
+    getUpdatesSince(docKey: DocumentKey, stateVector: Uint8Array): Uint8Array | null;
+    getEncodedState(docKey: DocumentKey): Uint8Array | null;
+    destroy(docKey: DocumentKey): void;
+    destroyAll(): void;
+    private getOrCreateState;
+    private static createDocumentState;
+    private handleTransportConnectionStateChange;
+    private markActiveDocumentsAsConnecting;
+    private replaySyncStep1ForActiveDocuments;
+    private requestSyncStep1;
+    /**
+     * Seed pending initial content into the Y.Doc. Returns true if content was seeded.
+     *
+     * Uses `origin` so the local update handler ignores the insert (prevents
+     * seeded content from being buffered as a pending local update).
+     */
+    private static seedPendingContent;
+    private static clearRetryTimer;
+    private static resetRetryState;
+    private scheduleRetrySyncStep1;
+    private attachLocalUpdateHandler;
+    private static detachLocalUpdateHandler;
+    private static isDocActive;
+    private shouldApplyRemoteMessage;
+    private sendIfConnected;
+    private setConnectionState;
+    private notifyContentChange;
+    private sendSyncStep1;
+    private sendUpdate;
+    private flushPendingLocalUpdates;
+    private handleMessage;
+    private handleSyncStep2;
+    private handleUpdate;
+    private handleError;
+    private getPersistedDocumentKey;
+    private restorePersistedDocument;
+    private persistDocument;
+}
+//# sourceMappingURL=document-manager.d.ts.map

package/dist/document-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-manager.d.ts","sourceRoot":"","sources":["../src/document-manager.ts"],"names":[],"mappings":"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"}